Script

You can automate your processes, such as executing HTTP requests using loops and conditions.

E.g., retrieve JSON from APIs, modify it using Vason query system and transmit it to the cloud.

The automation script is just simple javascript program, which you are writing by yourself.

You can debug your script by placing the debugger keyword somewhere in the script, and opening a browser's development tool.

Vason API

Additionally, there are non-blocking Vason API functions available for sequential execution mode, ensuring operation without blocking the GUI:

Service functions and variables

• VARS.<variable name> - set programmatically global variable, see the tab "HTTP variables"
• CONSOLE (<text or JSON>) - print text or JSON on console box
• CLEAR_CONSOLE() - clear console
• ERROR (<error message>) - print error message on console box
• SLEEP (<milliseconds, e.g. 2000 - 2 sec>) - pause script

HTTP Request functions

• REQ (<request description>, optional: <request body: string>) - send programmatically HTTP request, see the tab "HTTP requests"

  • 1st parameter - request description after "###" - 2nd parameter - request body only for POST/PUT requests

• BEFORE_REQ (<request description>, <function(requestObject) { ... }>) - register a request's BEFORE-hook, i.e. a function that can be executed before a request (see the tab "HTTP requests")

  • 1st parameter - the request description after "###" - 2nd parameter - a callback function that will be executed before the request and will also be triggered when executing the request from the "HTTP requests" tab. The callback function should have only one parameter, the request object with the properties: - url
  • the request url - method - the request method (GET, POST, PUT, DELETE) - headers
  • the request headers object in the format: <http header name>: <http header value>. This parameter can be empty object. - body - the request body. This parameter can be empty/null/undefined. - description - the request description after "###" You can set the "sendBodyAsBytes" property to "true" in a request object to send its body as a byte array It is not possible to use variables defined in the script root inside the "BEFORE_REQ" callback function definition

• AFTER_REQ (<request description>, <function(responseData, responseObject, requestObject) { ... }>) - register a request's AFTER-hook, i.e. a function that can be executed after a request (see the tab "HTTP requests")

  • 1st parameter - the request description after "###" - 2nd parameter - a function that will be executed after the request and will also be triggered when executing the request from the "HTTP requests" tab. The callback function should have the 3 parameters: - The response data: JSON, plain text or undefined - The response object with the fields: - status - the response status - statusText - the response status text - reason - the response reason - responseJSON - the response JSON
  • responseText - the response text - The request object with the fields: - url
  • the request url - method - the request method (GET, POST, PUT, DELETE) - headers
  • the request headers object in the format: <http header name>: <http header value>. This parameter can be empty object. - body - the request body. This parameter can be empty/null/undefined. - description - the request description after "###" It is not possible to use variables defined in the script root inside "AFTER_REQ" callback function definition

Query system functions

• QUERY (<json>,<query string>) - select/find value from json, or make the new json based on JSON parameter using Jsonata language

  • 1st parameter - json or variable with json to query - 2nd parameter - query string in jsonata format, see Analyze JSON data using the Jsonata queries and JSONata documentation - return - javascript object, array, number or string

Convert functions: string to string

With the help of the functions presented below, you can convert text from one format to another. The first column represents the function parameters, and the return values are in the header.

<parameter(P)>/return	JSON string	XML string	YAML string	TOML string
<JSON string>	PRETTIFY_JSON(<P>)	JSON_TO_XML(<P>)	JSON_TO_YAML(<P>)	JSON_TO_TOML(<P>)
<XML string>	XML_TO_JSON(<P>)	PRETTIFY_XML(<P>)	XML_TO_YAML(<P>)	XML_TO_TOML(<P>)
<YAML string>	YAML_TO_JSON(<P>)	YAML_TO_XML(<P>)	PRETTIFY_YAML(<P>)	YAML_TO_TOML(<P>)
<TOML string>	TOML_TO_JSON(<P>)	TOML_TO_XML(<P>)	TOML_TO_YAML(<P>)	PRETTIFY_TOML(<P>)

<parameter(P)>/return	BASE64 encoded string	any format string
<BASE64 encoded string>		BASE64_TO_STRING(<P>)
<any format string>	STRING_TO_BASE64(<P>)

Convert functions: string to/from object

Functions for converting objects to textual representation and vice versa

<parameter(P)>/return	string	JSON-object	XML-document
<string>		PARSE_JSON(<P>)	PARSE_XML(<P>)
<JSON-object>	STRINGIFY_JSON(<P>) or JSON_TO_STRING(<P>)
<XML-document>	STRINGIFY_XML(<P>) or XML_TO_STRING(<P>)

UI interact functions

Functions for interacting with editors in the right and left panels

<Source>/Destination	String	Left Editor	Right Editor
<String>		STRING_TO_LEFT_EDITOR(<P>)	STRING_TO_RIGHT_EDITOR(<P>)
<Left Editor>	LEFT_EDITOR_TO_STRING()
<Right Editor>	RIGHT_EDITOR_TO_STRING()

Example script

// There are non-blocking Vason API functions
// available for sequential execution mode,
// ensuring operation without blocking the GUI
// Click help button to see the complete documentation
// debugger // to debug your script place the "debugger"
// keyword somewhere and open a browser's development tool

/* -------------- example: request hooks -------------- */
function exampleBeforeHook(requestObject) {
  CONSOLE('Start request: ' + requestObject.description);
}

BEFORE_REQ('example receive access token', exampleBeforeHook);

AFTER_REQ(
  'example receive access token',
  (responseData, responseObject, requestObject) => {
    CONSOLE('End request: ' + requestObject.description);
    VARS.token = responseData.token;
    // you can also store a cookie this way
    // document.cookie = "token=" + data.token  + "; path=/"
  },
);

/* -------------- example: request and assign response to global variable -------------- */
// the variable can be assigne also in AFTER hook
VARS.token = REQ('example receive access token').token;

// pause 1 sec
SLEEP(1000);

// write to Vason console
CONSOLE('authorization token received: ' + VARS.token);

/* -------------- example: request and loop -------------- */
for (let planet of REQ('example get planets').planets) {
  /* -------------- example: query to make the new json -------------- */
  /* by using QUERY one can change one or more paticular properties in original json */
  var newPlanet = QUERY(
    planet,
    '$~>|**.extra|{"distance": $number(distance) * 1000000}|',
  );
  CONSOLE('update distance for planet: ' + newPlanet.name);
  SLEEP(1000);

  /* -------------- example: rquest with new body -------------- */
  var newDistance = REQ('example update planet', newPlanet).updatedObject.extra
    .distance;
  CONSOLE('new distance: ' + newDistance);
}

User interface

1. Console box
2. Script editor
3. Click to execute script
4. Click to interrupt script

Debug

1. Write debug in script and open Developer tools (e.g. in Chrome type Ctrl+Shift+I or Ctrl+Shift+C)
2. Click Execute script to start script
3. Analyze script in debug mode